home *** CD-ROM | disk | FTP | other *** search
MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) NNNNAAAAMMMMEEEE mdbm: mdbm_open, mdbm_close, mdbm_fetch, mdbm_store, mdbm_delete, mdbm_first, mdbm_firstkey, mdbm_next, mdbm_nextkey, mdbm_pre_split, mdbm_set_alignment, mdbm_limit_size, mdbm_invalidate, mdbm_close_fd, mdbm_sync, mdbm_lock, mdbm_unlock, mdbm_sethash- data base subroutines SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _cccc_cccc [_f_l_a_g ...] _f_i_l_e ... _----_llll_mmmm_dddd_bbbb_mmmm [_l_i_b_r_a_r_y ...] ####iiiinnnncccclllluuuuddddeeee <<<<mmmmddddbbbbmmmm....hhhh>>>> MMMMDDDDBBBBMMMM ****mmmmddddbbbbmmmm____ooooppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffiiiilllleeee,,,, iiiinnnntttt ffffllllaaaaggggssss,,,, mmmmooooddddeeee____tttt mmmmooooddddeeee,,,, iiiinnnntttt ppppaaaaggggeeeessssiiiizzzzeeee))));;;; vvvvooooiiiidddd mmmmddddbbbbmmmm____cccclllloooosssseeee((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; ddddaaaattttuuuummmm mmmmddddbbbbmmmm____ffffeeeettttcccchhhh((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; iiiinnnntttt mmmmddddbbbbmmmm____ssssttttoooorrrreeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____ddddeeeelllleeeetttteeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____ffffiiiirrrrsssstttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; ddddaaaattttuuuummmm mmmmddddbbbbmmmm____ffffiiiirrrrssssttttkkkkeeeeyyyy((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____nnnneeeexxxxtttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; ddddaaaattttuuuummmm mmmmddddbbbbmmmm____nnnneeeexxxxttttkkkkeeeeyyyy((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;; iiiinnnntttt mmmmddddbbbbmmmm____pppprrrreeee____sssspppplllliiiitttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, uuuuiiiinnnntttt66664444 ppppaaaaggggeeeessss,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____sssseeeetttt____aaaalllliiiiggggnnnnmmmmeeeennnntttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, iiiinnnntttt ppppoooowwwweeeerrrr))));;;; iiiinnnntttt mmmmddddbbbbmmmm____lllliiiimmmmiiiitttt____ssssiiiizzzzeeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, uuuuiiiinnnntttt66664444 ppppaaaaggggeeeessss,,,, iiiinnnntttt ((((****ffffuuuunnnncccc))))((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm ccccoooonnnntttteeeennnntttt,,,, vvvvooooiiiidddd ****pppprrrriiiioooorrrriiiittttyyyy))))))));;;; iiiinnnntttt mmmmddddbbbbmmmm____iiiinnnnvvvvaaaalllliiiiddddaaaatttteeee((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; vvvvooooiiiidddd mmmmddddbbbbmmmm____cccclllloooosssseeee____ffffdddd((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; vvvvooooiiiidddd mmmmddddbbbbmmmm____ssssyyyynnnncccc((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; iiiinnnntttt mmmmddddbbbbmmmm____lllloooocccckkkk((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; iiiinnnntttt mmmmddddbbbbmmmm____uuuunnnnlllloooocccckkkk((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; iiiinnnntttt mmmmddddbbbbmmmm____sssseeeetttthhhhaaaasssshhhh((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, iiiinnnntttt nnnnuuuummmmbbbbeeeerrrr))));;;; iiiinnnntttt mmmmddddbbbbmmmm____sssseeeetttt____cccchhhhaaaaiiiinnnn((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; PPPPaaaaggggeeee 1111 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) ddddaaaattttuuuummmm mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnn____ffffeeeettttcccchhhh((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnn____ffffiiiirrrrsssstttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnn____nnnneeeexxxxtttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; iiiinnnntttt mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnn____ssssttttoooorrrreeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm vvvvaaaallll,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnn____ddddeeeelllleeeetttteeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;; ddddaaaattttuuuummmm mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnnPPPP____ffffeeeettttcccchhhh((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnnPPPP____ffffiiiirrrrsssstttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; kkkkvvvvppppaaaaiiiirrrr mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnnPPPP____nnnneeeexxxxtttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv))));;;; iiiinnnntttt mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnnPPPP____ssssttttoooorrrreeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm vvvvaaaallll,,,, iiiinnnntttt ffffllllaaaaggggssss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____cccchhhhaaaaiiiinnnnPPPP____ddddeeeelllleeeetttteeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy))));;;; iiiinnnntttt mmmmddddbbbbmmmm____sssseeeetttt____ddddaaaattttaaaaffffoooorrrrmmmmaaaatttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, uuuuiiiinnnntttt8888____tttt ddddaaaattttaaaaffffoooorrrrmmmmaaaatttt))));;;; ddddaaaattttuuuummmm mmmmddddbbbbmmmm____tttteeeesssstttt____aaaannnndddd____sssseeeetttt((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, kkkkvvvvppppaaaaiiiirrrr kkkkvvvv,,,, ddddaaaattttuuuummmm ssssttttoooorrrraaaaggggeeee))));;;; iiiinnnntttt mmmmddddbbbbmmmm____ccccoooommmmppppaaaarrrreeee____aaaannnndddd____sssswwwwaaaapppp((((MMMMDDDDBBBBMMMM ****ddddbbbb ,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm oooollllddddvvvvaaaallll,,,, ddddaaaattttuuuummmm nnnneeeewwwwvvvvaaaallll))));;;; iiiinnnntttt mmmmddddbbbbmmmm____ccccoooommmmppppaaaarrrreeee____aaaannnndddd____ddddeeeelllleeeetttteeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, ddddaaaattttuuuummmm oooollllddddvvvvaaaallll))));;;; iiiinnnntttt mmmmddddbbbbmmmm____aaaattttoooommmmiiiicccc____bbbbeeeeggggiiiinnnn((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, ddddaaaattttuuuummmm kkkkeeeeyyyy,,,, mmmmddddbbbbmmmm____ggggeeeennnnlllloooocccckkkk____tttt ****ssssttttoooorrrraaaaggggeeee))));;;; iiiinnnntttt mmmmddddbbbbmmmm____aaaattttoooommmmiiiicccc____eeeennnndddd((((MMMMDDDDBBBBMMMM ****ddddbbbb))));;;; uuuuiiiinnnntttt33332222 mmmmddddbbbbmmmm____cccchhhheeeecccckkkk((((cccchhhhaaaarrrr ****ffffiiiilllleeee,,,, uuuuiiiinnnntttt33332222 ffffllllaaaaggggssss))));;;; uuuuiiiinnnntttt33332222 mmmmddddbbbbmmmm____rrrreeeeppppaaaaiiiirrrr((((cccchhhhaaaarrrr ****ffffiiiilllleeee,,,, uuuuiiiinnnntttt33332222 ffffllllaaaaggggssss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____bbbbyyyytttteeeessss____ppppeeeerrrr____ppppaaaaggggeeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, iiiinnnntttt ****ppppaaaaggggeeeessss))));;;; iiiinnnntttt mmmmddddbbbbmmmm____eeeelllleeeemmmm____ppppeeeerrrr____ppppaaaaggggeeee((((MMMMDDDDBBBBMMMM ****ddddbbbb,,,, iiiinnnntttt ****ppppaaaaggggeeeessss))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The mdbm routines are used to store key/content pairs in a high performance mapped hash file. Mdbm databases use fixed size pages, but the page size can be set on first open. The database does per page writer locking, and readers can detect and automaticly deal with writers. This allows for scalable multiple simultaneous readers and writers to be operating on the same mdbm file at the same time. Core functions are built into libc, the rest of them require linking with libmdbm. The functions in libc are: _m_d_b_m__c_l_o_s_e, _m_d_b_m__c_l_o_s_e__f_d, _m_d_b_m__f_e_t_c_h, _m_d_b_m__f_i_r_s_t, _m_d_b_m__f_i_r_s_t_k_e_y, _m_d_b_m__i_n_v_a_l_i_d_a_t_e, _m_d_b_m__n_e_x_t, PPPPaaaaggggeeee 2222 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) _m_d_b_m__n_e_x_t_k_e_y, _m_d_b_m__o_p_e_n, _m_d_b_m__s_e_t_h_a_s_h, _m_d_b_m__s_t_o_r_e, _m_d_b_m__s_y_n_c. Before a database can be accessed, it must be opened by _m_d_b_m__o_p_e_n. This will open and/or create the given file depending on the flags parameter (see _o_p_e_n(_2)). The pagesize parameter is a power of two between 8 (256 bytes) and 16 (65536 bytes). Once open, the data stored under a key is accessed by _m_d_b_m__f_e_t_c_h . The kvpair argument must be setup as follows: typedef struct { char *dptr; int dsize; } datum; typedef struct { datum key; datum val; } kvpair; kv.key.dptr should point to the key, and kv.key.dsize should be set to the length of the key. kv.val.dptr should point to allocated memory, which will be used to copy the result into. kv.val.dsize should be the size of the data. If kv.val.dptr is null, the returned datum's dsize field will bet set to the size of the value. It is always sufficient to allocate MDBM_PAGE_SIZE(db) bytes. A linear pass through all keys in a database may be made, in an (apparently) random order, by use of _m_d_b_m__f_i_r_s_t_k_e_y (_m_d_b_m__f_i_r_s_t) and _m_d_b_m__n_e_x_t_k_e_y(mdbm_next). _M_d_b_m__f_i_r_s_t_k_e_y will return the first key (key/content) in the database. _M_d_b_m__n_e_x_t_k_e_y will return the next key (key/content) in the database. Space for both the key (and the value) must be allocated as above. The following code will traverse the database retrieving every key and it's associated value. #include <mdbm.h> #include <alloca.h> int pagesize = MDBM_PAGE_SIZE(db); char *key = alloca(pagesize); char *val = alloca(pagesize); for (kv.key.dptr = key , kv.key.dsize=pagesize, kv.val.dptr = val, kv.val.dsize=pagesize, kv.key = mdbm_first(db,kv); key.dptr != NULL; kv.key.dptr = key , kv.key.dsize=pagesize, kv.val.dptr = val, kv.val.dsize=pagesize, kv.key = mdbm_next(db,kv)) It is possible to use mdbm_firstkey and mdbm_nextkey to traverse the database retriving only the keys. PPPPaaaaggggeeee 3333 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) Data is placed under a key by _m_d_b_m__s_t_o_r_e. The _f_l_a_g_s field can be either MMMMDDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT or MMMMDDDDBBBBMMMM____RRRREEEEPPPPLLLLAAAACCCCEEEE.... MMMMDDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT will only insert new entries into the database and will not change an existing entry with the same key. MMMMDDDDBBBBMMMM____RRRREEEEPPPPLLLLAAAACCCCEEEE will replace an existing entry if it has the same key. A key (and its associated contents) is deleted by _m_d_b_m__d_e_l_e_t_e. The mdbm_pre_split function can be used immediately after first open to expand the directory to a specified size. This helps to reduce the number of pages that will be split when storing a large amount of data. The pages parameter is a power of two for the depth of the tree. The ppppaaaaggggeeeessss parameter is used to compute the number of pages in the database. The formula for this is (2^pages). The contents may be forced to exist at a particular byte alignment using mdbm_set_alignment so that you can store structures in the database. The parameter is a power of two between 0 and 3. The only time this is needed is when accessing non-copied data from a mdbm file. This is not safe unless all access are protected by calls to mdbm_lock and mdbm_unlock, which is not recommended. The flags field can be 0 or MMMMDDDDBBBBMMMM____AAAALLLLLLLLOOOOCCCC____SSSSPPPPAAAACCCCEEEE.... MMMMDDDDBBBBMMMM____AAAALLLLLLLLOOOOCCCC____SSSSPPPPAAAACCCCEEEE attempts to pre-allocate blocks to back the file if it is on a holely filesystem. On the fly memory checking of mdbm database can be requested by passing the MMMMDDDDBBBBMMMM____MMMMEEEEMMMMCCCCHHHHEEEECCCCKKKK flag to _m_d_b_m__o_p_e_n. If this is done during the creation of a database, all subsequent opens of the database will inherit this requirement. This checking incurs a measurable performance penalty on all operations. All mdbm functions can operate in a synchronous mode by passing the OOOO____SSSSYYYYNNNNCCCC flag to mdbm_open. All changes to the database will case a _m_s_y_n_c(_2) of the appropriate section of the database to be performed. This incurs a significant performance penalty on all _m_d_b_m__s_t_o_r_e operations. The _m_d_b_m__l_i_m_i_t__s_i_z_e function can be used after first open to set a maximum size limit on the database. If supplied func is a function which will be called with each item on a page if an item needs to be stored, but there is no space. The priority argument is an integer between 1 and 3 giving the pass number. After three passes through the data, if space has not been freed the store will fail. The ppppaaaaggggeeeessss parameter is used to compute the number of pages in the database. The formula for this is (2^pages). _m_d_b_m__s_y_n_c simply forces the data to disk. Since the database is a mapped file most work is simply done in memory, and the state of the disk file is only guaranteed after mdbm_sync. _M_d_b_m__i_n_v_a_l_i_d_a_t_e should be called to mark a mdbm file as invalid or outdated. This should be done before unlinking the mdbm file. If this is not done long running programs that may have the mdbm file open will not detect that another process has remove the file. PPPPaaaaggggeeee 4444 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) If the database is a fixed size then the associated file descriptor can be closed using mdbm_close_fd. Otherwise the database will grow the file and possibly remap it into memory as data is added. The routines _m_d_b_m__l_o_c_k and _m_d_b_m__u_n_l_o_c_k can be used to synchronize access to an mdbm file. These use a very unsophisticated spinlock in the shared file to do the locking. It is almost always unnecessary to use these functions, and their use is highly discouraged. _m_d_b_m__s_e_t_h_a_s_h will set the has function of a database to number. This must be done immediately after creating the mdbm file. The default hash is 0. 0000 32 bit CRC. 1111 ejb's hsearch hash. Not recommended. 2222 Phong Vo's linear congruential hash. Good for short keys. 3333 Ozan Yigit's sdbm hash. Good for long keys. 4444 Torek's Duff device hash. Good for ASCII key. Bad for binary key. 5555 Fowler/Noll/Vo prime hash. Very good for keys under ~20 bytes. Under normal usage all mdbm databases have a limitation on the size of key/value pairs that can be stored. The available space for a single key/value pair is (pagesize - 10) bytes, where pagesize is determined by raising 2 to the pagesize argument passed to _m_d_b_m__o_p_e_n when the database is created. Thus with pagesize set to 7 a page is 128 bytes long (2^7 bytes), and with pagesize set to 12 a page is 4kb (2^12 bytes). If you know the maximum size of key/value pair that you will be storing then you should use this parameter to tune the mdbm database. If you dont know the maxium size of a key/value pair, then you should use the mdbm_chain interface described below. There is always a slight performance penalty when using the mdbm_chain interface. There are a number of functions that allow storage of unlimited size values via mdbm. These are the the _m_d_b_m__c_h_a_i_n_* functions. Before any keys are stored in an mdbm database, use the _m_d_b_m__s_e_t__c_h_a_i_n routine to enable this feature in a given database. Use _m_d_b_m__o_p_e_n and _m_d_b_m__c_l_o_s_e with a mdbm file that supports chaining. It is impossible to get a pointer to the copy of the data in the database by passing a NULL value. In this case the val.dsize field will be set to the size needed to retrieve the data. _m_d_b_m__c_h_a_i_n__f_e_t_c_h, _m_d_b_m__c_h_a_i_n__s_t_o_r_e, and _m_d_b_m__c_h_a_i_n__d_e_l_e_t_e behave similar to the non chaining versions. _m_d_b_m__c_h_a_i_n__f_i_r_s_t and _m_d_b_m__c_h_a_i_n__n_e_x_t do NOT return the value, and kv.val should have dptr set to NULL with dsize set to 0. On return dsize will be set to the size needed to copyout the data. PPPPaaaaggggeeee 5555 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) When chaining is enabled, the first character of a key may not start with a NULL byte unless the MMMMDDDDBBBBMMMM____CCCCHHHHAAAAIIIINNNN____NNNNUUUULLLLLLLL flag is passed to the _m_d_b_m__c_h_a_i_n__s_t_o_r_e function. All keys starting with NULL are ignored during _m_d_b_m__c_h_a_i_n__f_i_r_s_t and _m_d_b_m__c_h_a_i_n__n_e_x_t. There are a number of functions that will do the basic mdbm operations on mdbm files correctly supporting chaining if enabled for a given database. These are the _m_d_b_m__c_h_a_i_n_P_* functions. They can be used in place of the associated mdbm_* or mdbm_chain_* functions. The _m_d_b_m__s_e_t__d_a_t_a_f_o_r_m_a_t function allows a program to set a program specific database format identified that can be accessed with the (uint8_t) mmmmddddbbbbmmmm____ddddaaaattttaaaaffffoooorrrrmmmmaaaatttt ((((MMMMDDDDBBBBMMMM ****ddddbbbb)))) function. This dataformat is set to 0 by default, and is only used by programs makeing explict use of this feature. The _m_d_b_m__f_e_t_c_h, _m_d_b_m__f_i_r_s_t, _m_d_b_m__f_i_r_s_t_k_e_y, _m_d_b_m__n_e_x_t, _m_d_b_m__n_e_x_t_k_e_y, and _m_d_b_m__s_t_o_r_e functions as well as the mdbm_chain_* and mdbm_chainP_* counterparts are atomic in nature. There are a number of complex atomic operators that can fetch and store keys in an atomic manner. The _m_d_b_m__t_e_s_t__a_n_d__s_e_t function takes a new key/value pair, and sets key to the value. The current value of key will be returned in the storage provided. The _m_d_b_m__c_o_m_p_a_r_e__a_n_d__s_w_a_p function takes a key and compares the current value it is associated with with oldval. If they are exactly the same key will be set to newval. The _m_d_b_m__c_o_m_p_a_r_e__a_n_d__d_e_l_e_t_e is similar, but if the current value is oldval, the key will be delete. Atomic creates can be done with mdbm_store with the MDBM_INSERT flag set. The _m_d_b_m__a_t_o_m_i_c__b_e_g_i_n and _m_d_b_m__a_t_o_m_i_c__e_n_d functions allow complex atomic functions to be built. _m_d_b_m__a_t_o_m_i_c__b_e_g_i_n may be called multiple times for multiple keys. Then use the standard mdbm functions to access or modify these keys. Then call _m_d_b_m__a_t_o_m_i_c__e_n_d. Only one call to mdbm_atomic_end is required. The third argument is the address of storage large enough to hold a mdbm_genlock_t. It is suggested that this is the address of a variable on the stack. It is not safe to next mdbm_atomic operations. Do NOT call mdbm_compare_and_swap between _m_d_b_m__a_t_o_m_i_c__b_e_g_i_n and _m_d_b_m__a_t_o_m_i_c__e_n_d. Use of atomic operators increases the possibility that a program will crash while holding a database lock. If this happens a database can be checked and repaired. It is NNNNOOOOTTTT safe to repair a database while any other processes or threads are accessing it. But it is safe to check a database. The _m_d_b_m__c_h_e_c_k and _m_d_b_m__r_e_p_a_i_r functions work on a mdbm file and take a set of flags telling them what to check or try to repair. The functions return a set of flags telling what checked out bad, or was unrepairable. The output of _m_d_b_m__c_h_e_c_k can be used as the input flags to mdbm_repair. The macro _M_D_B_M__C_H_E_C_K__A_L_L requests that all possible error cases are check. _m_d_b_m__b_y_t_e_s__p_e_r__p_a_g_e, and _m_d_b_m__e_l_e_m__p_e_r__p_a_g_e take a pointer to an array of length MMMMDDDDBBBBMMMM____NNNNUUUUMMMMBBBBEEEERRRR____PPPPAAAAGGGGEEEESSSS (MDBM *db) which will be filled with the appropriate statistic. PPPPaaaaggggeeee 6666 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS All functions that return an _i_n_t indicate errors with negative values. A zero return indicates ok. Routines that return a _d_a_t_u_m indicate errors with a null (0) _d_p_t_r. If _m_d_b_m__s_t_o_r_e called with a _f_l_a_g_s value of MMMMDDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT finds an existing entry with the same key it returns 1. If there is an error during an mdbm call, the global error value eeeerrrrrrrrnnnnoooo will be set. The following errors will will be set. EEEEBBBBAAAADDDDFFFF During the open or access of a database the file version was not valid, or internal structures are invalid. This implies that the mdbm file is corrupted. EEEEBBBBAAAADDDDFFFFDDDD During the open of a database the file magic number was not valid. File is not a recognised mdbm file. EEEEBBBBUUUUSSSSYYYY During a _m_d_b_m__c_o_m_p_a_r_e__a_n_d__s_w_a_p or _m_d_b_m__c_o_m_p_a_r_e__a_n_d__d_e_l_e_t_e the current value in the database is not oldval. EEEEDDDDEEEEAAAADDDDLLLLKKKK A accessed page was locked, and after a number of attempts did not become unlocked. EEEEDDDDEEEEAAAADDDDLLLLOOOOCCCCKKKK During a page lock, a livelock was detected and held locks may have been broken. EEEEEEEEXXXXIIIISSSSTTTT A store with the MMMMDDDDBBBBMMMM____IIIINNNNSSSSEEEERRRRTTTT flag set failed since the key already exists. A function that changes header parameters is attempted when there is data already stored in the database. EEEEIIIINNNNVVVVAAAALLLL An invlid argument was passed. EEEENNNNOOOOEEEEXXXXIIIISSSSTTTT The requested key does not exist in the database. EEEENNNNOOOOLLLLCCCCKKKK A request to find the lock on a page that should be locked by the current process failed. EEEENNNNOOOOMMMMEEEEMMMM Internal allocation of memory failed. The only allocation that is performed is the MDBM structure that is returned by _m_d_b_m__o_p_e_n which is freed by _m_d_b_m__c_l_o_s_e. EEEENNNNOOOOSSSSPPPPCCCC There is insufficient space in the database to store the requested key or if no shake function is defined for a fixed size database. EEEEPPPPEEEERRRRMMMM Permission to perform a write to the mdbm file is denied. EEEESSSSTTTTAAAALLLLEEEE The mdbm file has been invalidated. It is suggested that an attempt to re-open the database should be made, since a writing process may invalidate an mdbm file, and create a new one with the same filename. PPPPaaaaggggeeee 7777 MMMMDDDDBBBBMMMM((((3333BBBB)))) MMMMDDDDBBBBMMMM((((3333BBBB)))) CCCCAAAAVVVVEEEEAAAATTTTSSSS The file is designed to contain holes in files. The EFS file system does not implement holes, so the file will frequently be significantly larger than the actual content. The sum of the sizes of a key/content pair must not exceed the internal block size (defaults to 4096 bytes). Moreover all key/content pairs that hash together must fit on a single page. The page size can be set to a maximum of 64KB on first open. _M_d_b_m__s_t_o_r_e will return an error in the event that a disk block fills with inseparable data. The order of keys presented by _m_d_b_m__f_i_r_s_t, _m_d_b_m__f_i_r_s_t_k_e_y, _m_d_b_m__n_e_x_t and _m_d_b_m__n_e_x_t_k_e_y depends on a hashing function and the order they were stored in the database, not on anything interesting. _M_d_b_m__d_e_l_e_t_e does not physically reclaim file space, although it does make it available for reuse. It is incorrect to truncate a mdbm database. The correct procedure is to create a new database, open the old database, rename the new database on top of the old database, invalidate the old database, unlink the old database. PPPPaaaaggggeeee 8888 
